Graphics Plus

home *** CD-ROM | disk | FTP | other *** search

/ Graphics Plus / Graphics Plus.iso / general / modelers / geomview / source.lha / Geomview / src / lib / mg / mg.doc < prev

Wrap

Text File | 1993-02-04 | 23.9 KB | 674 lines

$Id: mg.doc,v 1.14 1993/02/04 00:43:29 slevy Exp $ MinneGraphics (MG) The Geometry Center July 1991 mbp, slevy, Sun Jul 21 15:16:25 1991 This document defines MG. MG is a graphics library which provides a common interface for doing interactive 3D graphics on a variety of platforms. The main intent is that it will be used with OOGL (Object Oriented Graphics Lanauge), but there is nothing OOGL-specific about MG, and conceivably other applications could use it as well. MG is not meant to be as general or powerful as other 3D graphics lanuages such as GL, XGL, RenderMan, PHIGS, etc. --- rather it is meant to provide access to the most important operations common to all of these languages. MG is deliberately simple. It is *not* an attempt to solve the 3D graphics standardization problem. Until a widely accepted standard does emerge, MG is an attempt to insulate ourselves from the specifics of individual graphics lanuages, allowing us to write programs that will run under a variety of these languages. MG consists of several parts: a common part, and a part for each device (language) on which it it implemented. The library files are constructed so that each device-specific library includes the common part, so the application program only needs to link in the libraries corresponding to the devices it wants to use (there is no separate "common" library). Any application program using MG should include the header file "mg.h". The rest of this file contains a list of the MG procedures with a description of the call syntax and an explanation of what each procedure does. This list is meant to be used both in writing MG application modules and in writing MG device-drivers. Most MG procedures have several versions. The following conventions are used in referring to them. 1. application version name convention: mgproc This is the version of the procedure which application programs call. In most cases the name "mgproc" is actually a #define macro which expands to a function pointer which points to the corresponding device-specific version of proc. Application programs should only call these versions of MG procedures (the one exception is mgdevice_XX, for which there is only a device-specific version). 2. common version name convention: mg_proc This is a version of proc which performs operations, frequently bookkeeping type things, common to all MG devices. The device-specific version of proc may call the common version to accomplish these operations. For the details of what the common mg_proc does, including information on when the device-specific version should call it, see the documentation of the source code for mg_proc in the mg/common directory. The common procedures also serve as the "null device". Before a device has been specified in an MG application program, the application version of proc is a pointer to the common procedure. Running the program in this state draws no graphics but accomplishes all other operations associated with MG. 3. device version name convention: mgxx_proc, where xx = device (GL, XGL, etc). This is the version of proc specific to device xx. It accomplishes the actual graphics operations, and calls the corresponding common routine if/when necessary to perform common operations. To write a new MG device driver you must supply a version of each device procedure for the new device. The call syntax of each of these versions of proc is identical; the prototypes below are given in terms of the application version. APPLICATION COMMON DEVICE VERSION VERSION VERSION ----------------- ------- --------------- General control and informational procedures: mgbegin mg_begin NONE ??? (1) mgend mg_end NONE ??? (1) NONE NONE mgdevice_XX mgsync mg_sync mgxx_sync mgworldbegin mg_worldbegin mgxx_worldbegin mgworldend mg_worldend mgxx_worldend mgfeature mg_feature mgxx_feature Procedures related to creating and modifying the graphics context: mgctxcreate mg_ctxcreate mgxx_ctxcreate mgctxtcopy mg_ctxcopy NONE mgctxdelete mg_ctxdelete mgxx_ctxdelete mgctxselect mg_ctxselect mgxx_ctxselect mgctxset mg_ctxset mgxx_ctxset mgctxget mg_ctxget mgxx_ctxget mgpushappearance mg_pushappearance mgxx_pushappearance mgpopappearance mg_popappearance mgxx_popappearance mgsetappearance mg_setappearance mgxx_setappearance mgsetcamera mg_setcamera mgxx_setcamera mgidentity mg_identity mgxx_identity mgtransform mg_transform mgxx_transform mgpushtransform mg_pushtransform mgxx_pushtransform mgpoptransform mg_poptransform mgxx_poptransform mgsettransform mg_settransform mgxx_settransform mggettransform mg_gettransform mgxx_gettransform mgreshapeviewport mg_reshapeviewport mgxx_reshapeviewport Graphics primitives: mgpolygon mg_polygon mgxx_polygon mgmesh mg_mesh mgxx_mesh mgline mg_line mgxx_line mgpolyline mg_polyline mgxx_polyline mgpolylist mg_polylist mgxx_polylist mgquads mg_quads mgxx_quads mgbezier mg_bezier mgxx_bezier ======================================================================== /*----------------------------------------------------------------------- * Function: mgfeature * Description: tests whether the current device has a particular feature * Args: feature: * Returns: a value that indicates something about the feature; * -1 means the feature is not present. * Author: slevy, mbp * Date: Thu Jul 18 20:29:34 1991 * Notes: At present, only one feature is defined: * Feature Returned Value * MGF_BEZIER 1 if mgbezier() supported, else -1. * * Others are contemplated, for example: * MGF_ZBUFFER Depth of Z buffer * MGF_BITPLANES Number of bitplanes * MGF_DOUBLEBUFFER 1 for yes, -1 for no * etc etc etc */ int mgfeature(int feature) /*----------------------------------------------------------------------- * Function: mgctxcreate * Description: create a graphics context * Args: a1, ...: list of (attribute, value) pairs, terminated by * MG_END * Returns: pointer to the new graphics context * Author: slevy, mbp * Date: Thu Jul 18 20:34:28 1991 * Notes: The created context becomes the current context. The * attributes specified in the list are set as though * they had been passed to mgctxset; see mgctxset * for an explanation of what attributes are allowed. * * Device must be set, via a call to mgdevice_GL, * mgdevice_PS, etc, before creating a new context. Once * created, a context is valid only for the device for which * it was created. * * The value returned is a pointer to an opaque structure; * it should not be modified in any way. The only thing * you can legitimately do with this pointer is pass it * to other MG procedures, such as mgctxselect. * * The MG_SHOW attribute is set to 1 by default, which means * that (for relevant devices) the context's window becomes * visible on the screen when mgctxcreatec is called. * To prevent the window from appearing in the call to * mgctxcreate, set MG_SHOW to 0. Then call mgctxset * to set MG_SHOW to 1 to make the window appear later. * * Note: a1 is simply the first attribute in the list of * (attribute, value) pairs. It is listed as a separate * argument because of the way stdarg works. */ mgcontext *mgctxcreate(a1, ... /*, MG_END */) /*----------------------------------------------------------------------- * Function: mgctxcopy * Description: copy one context to another * Args: *src: the source context * *dst: the destination context * Returns: nothing * Author: mbp * Date: Mon Jul 22 11:01:32 1991 * Notes: Everything associated with the source context * is copied into the destination context, EXCEPT the * device setting. * * This is a shallow copy --- ctx attributes which are * pointers (e.g. the camera and window pointers) are * copied as pointers, so that those attributes in dest * point to the same structures as the corresponding src * attributes. * * There is no device version of mgctxcopy. */ mgctxcopy(mgcontext *src, mgcontext *dst) /*----------------------------------------------------------------------- * Function: mgctxdelete * Description: delete a context * Args: ctx: pointer to the context to delete * Returns: nothing * Author: slevy, mbp * Date: Sun Jul 21 15:33:07 1991 * Notes: ctx should be the pointer returned by mgctxcreate * when the context was created. This procedure frees up * all space associated with ctx. After * mgctxdelete(ctx), ctx will be an invalid pointer. */ void mgctxdelete(mgcontext *ctx) /*----------------------------------------------------------------------- * Function: mgctxset * Description: set some attributes in the current context * Args: a1, ...: list of (attribute, value) pairs, terminated by MG_END * Returns: nothing * Author: slevy, mbp * Date: Fri Jul 19 15:50:46 1991 * Notes: Attributes are documented in the file mg.attr. * Note: a1 is simply the first attribute in the list * of (attribute, value) pairs. It is listed as a * separate argument because of the way stdarg works. * The list of attributes MUST end with MG_END. */ void mgctxset(a1, ... /*, MG_END */) /*----------------------------------------------------------------------- * Function: mgctxget * Description: get the value of an attribute in the current context * Args: attr: the attribute to get * valueptr: pointer to location to write value to * Returns: number of bytes written to address valueptr; 0 means * invalid attr * Author: slevy, mbp * Date: Fri Jul 19 16:26:32 1991 * Notes: valueptr should be the address of an object of the type * associated with the attribute attr; the object at * that address will be overwritten with the value in * the current context. See mg.attr for a list of * attributes. */ int mgctxget(int attr, void* valueptr) /*----------------------------------------------------------------------- * Function: mgctxselect * Description: Set the current graphics context to ctx * Args: ctx: ptr to the context to make current * Returns: ctx, or NULL if unsuccessful * Author: slevy, mbp * Date: Fri Jul 19 11:48:13 1991 * Notes: Does not copy *ctx --- just sets the internal pointer * _mgc to ctx, and calls any device-specific procedures * neccessary to bring the device into the state * corresponding to context *ctx. * Also changes the current device to be the device * associated with *ctx. */ int mgctxselect(mgcontext *ctx) /*----------------------------------------------------------------------- * Function: mgsync * Description: Insures that all mg graphics operations have been sent to * the device, and instructs the device to process them * Args: (none) * Returns: nothing * Author: slevy, mbp * Date: Fri Jul 19 12:14:09 1991 * Notes: The idea behind mgsync is that it could be used, * for example, to guarantee (in singlebuffer mode) * that everything that has * been drawn so far is actually visible in the window. * It might also be necessary for telling mg and/or the * device to flush any internal buffering of graphics * operations. * * mgsync is called implicitly by mgworldend. */ void mgsync() /*----------------------------------------------------------------------- * Function: mgworldbegin * Description: Prepare to draw in the current context * Args: (none) * Returns: nothing * Author: slevy, mbp * Date: Fri Jul 19 12:49:12 1991 * Notes: mgworldbegin must be called before any mg drawing commands. * It erases the current window to the background color and * clears any internal (to the device) records associated with * drawing. Also interprets the current camera setting; all * graphics operations after mgworldbegin and before the next * mgworldend will be displayed using this camera setting. * * The process of drawing an image on the current window * is bracketed by calls to mgworldbegin and mgworldend: * mgworldbegin(); * draw draw draw; * mgworldend(); <-- image is complete here */ void mgworldbegin() /*----------------------------------------------------------------------- * Function: mgworldend * Description: end the group of graphics operations begun with * mgworldbegin * Args: (none) * Returns: nothing * Author: slevy, mbp * Date: Fri Jul 19 13:01:00 1991 * Notes: Guarantees that all operations done since mgworldbegin * become visible. In doublebuffer mode, this involves * swapping the buffers. Implicitly calls mgsync. * Some devices might buffer graphics operations, and only * interpret them when mgworldend is called. */ void mgworldend() /*----------------------------------------------------------------------- * Function: mgreshapeviewport * Description: adjust internal window & camera * Args: (none) * Returns: nothing * Author: slevy, mbp * Date: Fri Jul 19 13:11:29 1991 * Notes: Intended for use in window systems where the user may * dynamically reshape, resize, or move the window. Causes * the window (MgWindow) size and position, and the camera * aspect ratio associated with the current context to be * updated to reflect the actual shape and size of the window. */ void mgreshapeviewport() /*----------------------------------------------------------------------- * Function: mgidentity * Description: sets the current context's object xform to I * Args: (none) * Returns: nothing * Author: slevy, mbp * Date: Fri Jul 19 13:19:43 1991 */ void mgidentity() /*----------------------------------------------------------------------- * Function: mgtransform * Description: mult (on the left) the current object xform by T * Args: T * Returns: nothing * Author: slevy, mbp * Date: Fri Jul 19 13:21:40 1991 * Notes: Suppose that before mgtransform is called, the * current transform is A, so that object row vector v * is mapped to v A. Then after mgtransform(T), * v will be mapped to v T A. * * Note that this means that Euclidean translations * appear in the 4th row of the transform matrix * (rather than in the 4th column). * * [This differs from the old mg convention, * so old programs may need to be changed. However * the new convention matches the ASCII format we use * for matrices, and also matches the internal formats * used by SGI, Sun, and QuickRenderman.] */ void mgtransform(const Transform T) /*----------------------------------------------------------------------- * Function: mgpushtransform * Description: Push a copy of the current xform onto the current * context's xform stack * Args: (none) * Returns: the new depth of the stack ??? * Author: slevy, mbp * Date: Fri Jul 19 13:30:24 1991 * Notes: before after * A A <-- top * B A * C B * C * * Stack might have limited depth --- usually depends on the * device. */ int mgpushtransform() /*----------------------------------------------------------------------- * Function: mgpoptransform * Description: Pop the current context's xform stack * Args: (none) * Returns: the new depth of the stack ???? * Author: slevy, mbp * Date: Fri Jul 19 13:39:04 1991 */ int mgpoptransform() /*----------------------------------------------------------------------- * Function: mggettransform * Description: set the current context's current xform * Args: T: the xform * Returns: nothing * Author: slevy, mbp * Date: Fri Jul 19 13:44:18 1991 */ void mgsettransform(Transform T) /*----------------------------------------------------------------------- * Function: mggettransform * Description: get the current context's current xform * Args: T: the xform * Returns: the depth of the xform stack ???? * Author: slevy, mbp * Date: Fri Jul 19 13:44:18 1991 * Notes: The current xform is the one on the top of the stack. */ int mggettransform(Transform T) /*----------------------------------------------------------------------- * Function: mgpushappearance * Description: Push a copy of the current attr onto the current * context's appearance stack * Args: (none) * Returns: the new depth of the appearance stack ???? * Author: slevy, mbp * Date: Fri Jul 19 13:45:19 1991 * Notes: Like mgpushtransform, but works with the appearance stack * instead. */ int mgpushappearance() /*----------------------------------------------------------------------- * Function: mgpopappearance * Description: Pop the current context's appearance stack * Args: (none) * Returns: the new depth of the stack ???? * Author: slevy, mbp * Date: Fri Jul 19 13:39:04 1991 */ int mgpopappearance() /*----------------------------------------------------------------------- * Function: mgsetappearance * Description: merge or set current Appearance * Args: app: Appearance to merge or copy * mergeflag: copy or merge app into current Appearance? * Returns: nothing * Author: slevy, mbp * Date: Fri Jul 19 13:55:15 1991 * Notes: If mergeflag==MG_SET, sets the current Appearance to * exactly match *app. If mergelfag==MG_MERGE, sets the current * Appearance to the union of itself with *app. * For fields for which both the current Appearance * and *app have values, *app takes precedence, unless * the override bit is set for that field in the * current Appearance. */ void mgsetappearance(Appearance* app, int mergeflag) /*----------------------------------------------------------------------- * Function: mgsetcamera * Description: set the current camera * Args: cam: * Returns: nothing * Author: slevy, mbp * Date: Fri Jul 19 14:06:29 1991 * Notes: New camera will not actually be used until next * mgworldbegin. */ int mgsetcamera(Camera* cam) /*----------------------------------------------------------------------- * Function: mgpolygon * Description: draw a polygon * Args: nv: number of vertices * *v: array of nv vertices * nn: number of normals (should be either 0, 1, or nv) * *n: array of nn normals (ignored if nn==0) * nc: number of colors (should be either 0, 1, or nv) * *c: array of nc ColorA's (ignored if nc==0) * Returns: nothing * Author: slevy, mbp * Date: Fri Jul 19 16:41:24 1991 */ void mgpolygon(int nv, Point3 *v, int nn, Point3 *n, int nc,ColorA *c) /*----------------------------------------------------------------------- * Function: mgmesh * Description: draw a mesh * Args: wrap: either MM_NOWRAP for no wrapping * or MM_UWRAP for wrapping in the u direction (cylinder) * or MM_VWRAP for wrapping in the v direction (cylinder) * or MM_UWRAP+MM_VWRAP for wrapping in both dirs (torus) * nu: number of vertices in the u direction * nv: number of vertices in the v direction * p: array of nu*nv vertices in v-major order (u index * increases fastest) * n: array of nu*nv normals (same order as *p), or NULL * c: array of nu*nv ColorA's (same order as *p), or NULL * Returns: nothing * Author: slevy, mbp * Date: Fri Jul 19 16:44:57 1991 * Notes: if n is NULL, normals are not supplied to the device. * if c is NULL, then the color settings in the current * default Appearance apply. */ void mgmesh(int wrap,int nu,int nv,Point3 *p,Point3 *n,ColorA *c) /*----------------------------------------------------------------------- * Function: mgline * Description: draws a line * Args: *p1: first endpoint of line * *p2: second endpoint of line * Returns: nothing * Author: slevy, mbp * Date: Fri Jul 19 16:54:50 1991 */ void mgline(Point3 *p1, Point3 *p2) /*----------------------------------------------------------------------- * Function: mgpolyline * Description: draws a polyline * Args: nv: number of vertices * *verts: array of nv vertices * nc: number of colors (should be 0, 1, or nv) * *colors: array of nc colors * flags: bit-encoded: * flags&1 indicates that this polyline is a closed curve; * an extra vector should be drawn connecting the * first and last points. * Other bits are available as hints the mg driver may use * to optimize the work done in drawing: * flags&2 indicates that this is not the first of a * batch of related polylines. It might be sufficient * to initialize the drawing color for only the first * polyline in a batch; also, if the driver handles * displacing lines closer to the eye, then the transform * might be pushed before the first polyline of a batch * and popped after the last one. * flags&4 indicates that this is not the last of a * batch of related polylines. * Returns: nothing * Author: slevy, mbp * Date: Fri Jul 19 16:56:33 1991 */ void mgpolyline(int nv, Point3 *verts, int nc, ColorA *colors, int flags) /*----------------------------------------------------------------------- * Function: mgpolylist * Description: draws a PolyList * Args: npolys: number of Poly structures (one per polygon) * *polys: array of Poly structures from polylist.h. * flags: indicates which Poly & Vertex fields are valid; * bitwise union of PL_HAS{P,V}{N,COL} from polylist.h. * Returns: nothing * Author: slevy * Date: Mon Aug 19 15:16:44 CDT 1991 */ void mgpolylist(int npolys, Poly *polys, int flags) /*----------------------------------------------------------------------- * Function: mgquads * Description: draws an array of Quads * Args: nquads: number of Poly structures (one per polygon) * *v: array of 4*nquads HPoint3's, the quads' vertices * *n: array of 4*nquads Point3's, their normals - or NULL * *c: array of 4*nquads ColorA's, their colors - or NULL * Returns: nothing * Author: slevy * Date: Mon Jul 17 23:16:20 CDT 1992 * Note: This routine was added to optimize quad drawing. */ void mgquads(int nquads, HPoint3 *v, Point3 *n, ColorA *c) /*----------------------------------------------------------------------- * Function: mgbezier * Description: draws a bezier for those drivers which support it * Args: degree_u: degree in u direction * degree_v: degree in v direction * dimension: dimension * *controlPoints: array of control points * *txmapst: array of 4 (s,t) float pairs for texture map * coordinates for each corner of map * *colors: array of 4 ColorA structs or NULL * Returns: nothing * Author: wisdom (from munzners older code) * Date: Sat Sep 19 16:37:08 CDT 1992 * Notes: Currently, the bezier is drawn blah blah * For those drivers which do not support beziers, the * bezier is diced and drawn as a mesh (common code default). */ void mgbezier(int degree_u, int degree_v, int dimension, float *ControlPoints, float *txmapst, ColorA *colors) /*----------------------------------------------------------------------- * Function: mgbegin * Description: intialize MG * Args: (none) * Returns: nothing * Author: slevy, mbp * Date: Fri Jul 19 18:27:39 1991 * Notes: Must be called exactly once, before any other mg * functions */ mgbegin() /*----------------------------------------------------------------------- * Function: mgdevice_XX * Description: select device xx * Args: (none) * Returns: nothing * Author: slevy, mbp * Date: Fri Jul 19 18:28:52 1991 * Notes: Must be called after mgbegin and before mgcreatecontext. * If the current context is for a device other than xx, * it is de-selected. * See mg.h for list of valid devices allowed for xx. */ mgdevice_XX() /*----------------------------------------------------------------------- * Function: mgend * Description: shut down MG * Args: (none) * Returns: nothing * Author: slevy, mbp * Date: Fri Jul 19 18:31:34 1991 * Notes: Call once after all other mg calls. */ mgend() =========================================================================== (1) should we go ahead and be systematic and have mgxx_begin and mgxx_end and decree that each should call the common routine of the same name? (device begin/end inside common begin/end). Done: renamed mgcopycontext to mgctxcopy mgselectcontext to mgctxselect mgsetAp to mgsetappearance mgsetCam to mgsetcamera added MG_SET and MG_MERGE for merge flag to setappearance. Too much confusion over whether 0 or 1 means set or merge!!